Pull request overview

Restores and integrates the HGraph conjugate-graph enhancement end-to-end (parameters, feedback/pretrain APIs, search-time result enhancement, and binary/streaming serialization), plus updates example and EN/ZH docs.

Changes:

• Added HGraph build/search parameters to enable conjugate-graph construction and toggled search-time usage.
• Implemented Feedback/Pretrain/UpdateId conjugate-graph integration, including streaming/binary serialization and memory accounting.
• Migrated the C++ runnable example and synchronized English/Chinese documentation for the feature.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 7 comments.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Code review for feat(hgraph): restore conjugate graph enhancement

Automated review by vsag-pr-review-agent

Code review for PR #2675.

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

        while (not label_results.empty()) {
            const auto record = label_results.top();
            label_results.pop();
            const auto [found, inner_id] = this->label_table_->TryGetIdByLabel(record.second, true);
            if (found and (ft == nullptr or ft->CheckValid(inner_id))) {

    std::shared_ptr<vsag::Index> hgraph;
    if (auto index = vsag::Factory::CreateIndex("hgraph", hgraph_build_parameters);
        index.has_value()) {
        hgraph = index.value();
    } else {

Review Summary

This PR restores conjugate graph enhancement for HGraph with comprehensive coverage: Feedback/Pretrain methods, search-time enhancement integration, UpdateId support, memory accounting, and both binary and streaming serialization. The implementation is well-structured and the test coverage is thorough.

Issues from previous review rounds

All previously reported issues have been addressed:

• Lock ordering: label_lookup_mutex_ is consistently acquired before conjugate_graph_mutex_ across all code paths (Feedback, Pretrain, UpdateId, search enhancement).
• Filter semantics: The enhancement result rebuild now holds a shared label lock and re-checks ft->CheckValid(inner_id) before pushing results back.
• Performance: flatten and computer are created once outside the per-label lambda.
• Streaming deserialization: Now correctly rejects a conjugate-graph block when the target HGraph was created without the feature, matching binary deserialization behavior.
• Typo fix: "constains" → "contains" in the example.

Current assessment

The code is clean, well-tested, and all critical concerns from earlier rounds have been resolved. No new issues found in this revision.

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

    StreamWriter::WriteObj(out_stream, memory_usage_);
    for (const auto& [tag_id, neighbor_ptr] : conjugate_graph_) {
        StreamWriter::WriteObj(out_stream, tag_id);
        uint64_t neighbor_set_size = neighbor_ptr->size();
        StreamWriter::WriteObj(out_stream, neighbor_set_size);
        for (const auto neighbor_tag_id : *neighbor_ptr) {
            StreamWriter::WriteObj(out_stream, neighbor_tag_id);
        }
    }

    std::stringstream footer_stream(std::ios::in | std::ios::out | std::ios::binary);
    footer_.Serialize(footer_stream);
    const auto footer_data = footer_stream.str();
    out_stream.Write(footer_data.data(), footer_data.size());
}

        std::shared_lock label_lock(this->label_lookup_mutex_);
        while (not search_result->Empty()) {
            const auto record = search_result->Top();
            search_result->Pop();
            label_results.emplace(record.first, this->label_table_->GetLabelById(record.second));
        }

        const auto flatten = use_custom_distance ? nullptr : this->get_precise_codes();
        const auto computer = use_custom_distance ? nullptr : flatten->FactoryComputer(raw_query);
        const auto distance_of_label = [&](int64_t label) {
            const auto [found, inner_id] = this->label_table_->TryGetIdByLabel(label, true);
            if (not found or (ft != nullptr and not ft->CheckValid(inner_id))) {
                return std::numeric_limits<float>::max();
            }
            float distance = std::numeric_limits<float>::max();
            if (use_custom_distance) {
                request.distance_batch_func_(&label, 1, &distance);
            } else {
                flatten->Query(&distance, computer, &inner_id, 1, &ctx);
            }
            if (request.threshold_.has_value() and distance > request.threshold_.value()) {
                return std::numeric_limits<float>::max();
            }
            return distance;
        };
        {
            std::shared_lock graph_lock(this->conjugate_graph_mutex_);
            (void)this->conjugate_graph_->EnhanceResult(label_results, distance_of_label);
        }
        while (not label_results.empty()) {
            const auto record = label_results.top();
            label_results.pop();
            const auto [found, inner_id] = this->label_table_->TryGetIdByLabel(record.second, true);
            if (found and (ft == nullptr or ft->CheckValid(inner_id))) {
                search_result->Push(record.first, inner_id);
            }
        }

    std::shared_ptr<vsag::Index> hgraph;
    if (auto index = vsag::Factory::CreateIndex("hgraph", hgraph_build_parameters);
        index.has_value()) {
        hgraph = index.value();
    } else {
        std::cout << "Create HGraph Error" << std::endl;
    }

经过对最新 commit (3311525) 的全面审查，确认之前 Copilot 和其他 reviewer 发现的所有重要问题都已在修正后的代码中得到解决：

已确认修复的问题：

1. 锁顺序问题 — Feedback 中现在正确使用 label_lookup_mutex_ (shared) → conjugate_graph_mutex_ (unique) → memory_usage_mutex_ (unique) 的顺序
2. 过滤语义 — conjugate graph 增强后重新检查 is_allowed(inner_id) 再 push 回结果
3. flatten/computer 性能 — 在 lambda 外部创建，避免重复构造
4. label-table 无锁访问 — Pretrain 中已使用 TryGetIdByLabel 并持有 label_lookup_mutex_
5. streaming deserialization 一致性 — 现在 streaming 路径也拒绝 mismatched conjugate graph 块
6. 示例 typo — 已修正
7. memory_usage_ 溢出 — AddNeighbor 中已添加 overflow check
8. UpdateId 锁范围 — 已缩小为仅包裹 conjugate graph 更新

代码质量评估：

• 新文件 hgraph_enhance.cpp 结构清晰，错误处理完善
• 序列化支持完整（binary + streaming），版本兼容性处理得当
• 测试覆盖全面：基本功能、并发安全、range search 不受影响、参数解析、序列化往返
• 内存统计正确集成到 cal_memory_usage() 和 GetMemoryUsageDetail()
• 参数映射遵循现有模式，CheckCompatibility 正确包含 use_conjugate_graph

没有发现新的阻塞性问题。

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.